{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Lecture 7 : Classes and algebraic structures\n",
    "**References:**\n",
    "* [Tutorial: Objects and Classes in Python and Sage](https://doc.sagemath.org/html/en/thematic_tutorials/tutorial-objects-and-classes.html)\n",
    "* [How to implement new algebraic structures in Sage](https://doc.sagemath.org/html/en/thematic_tutorials/coercion_and_categories.html)\n",
    "* [Primer on categories, parents and elements in SageMath](https://doc.sagemath.org/html/en/reference/categories/sage/categories/primer.html)\n",
    "\n",
    "**Summary:**<br>\n",
    "In this lecture, we discuss how to define new **classes** in Python (and SageMath). We learn how to give them useful **methods** and how to **inherit** from other classes. We discuss how to implement **arithmetic operations** in Python and, if time permits, how to use the parent/element framework in SageMath to implement more general **algebraic structures** there."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A brief overview of classes\n",
    "Without discussing it in much detail, we have already used many examples of classes defined in SageMath. Take the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 6/5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "type(a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that there exists a **class** (namely ``Rational``, defined in ``sage.rings.rational``) which implements rational numbers. The concrete **object** ``a`` that we created is an **instance** of this class. \n",
    "\n",
    "One of the things that we can do now is use **methods** of the class above, for the specific instance ``a`` that we created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.factor()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code for this particular method forms part of the class ``Rational``, and we can have a look at the corresponding code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a.factor??"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we want to learn how to create such nice classes for ourselves!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating new classes\n",
    "Our running example will be a toy implementation of the complex numbers. Here is a first basic version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's certainly very basic! Still, we see some of the important structure:\n",
    "* We begin with the keyword ``class`` followed by the name that we choose and a ``:``. In the following indented block, we can define methods of our new class.\n",
    "* The most fundamental method is always called ``__init__``, which is used when creating new instances of our class (i.e. when we create a new object representing a complex number). Its first argument is always ``self``, which will be this new instance, followed by some more arguments. In the case above, these are the inputs ``RealPart, ImaginaryPart`` of the real and imaginary part of our complex number. What our concrete method above does is simply to store these values inside ``self`` as **attributes** ``self.Re, self.Im``. \n",
    "\n",
    "Let's see this class in \"action\". First, we create a new instance, representing the number $1+2\\cdot i$, and call it ``z``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = MyCompNumb(1, 2)\n",
    "type(z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our class cannot do anything interesting yet, but we *can* access the internal attributes ``Re, Im``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z.Re"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These more or less work like any variables that we used before, e.g. we can also change their values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z.Re = 3\n",
    "z.Re"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most of the rest of the lecture, we will discuss how to make this class more interesting and usable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing methods\n",
    "The main feature of classes is that we can give them methods, i.e. functions defined inside the class, which we can call like ``a.factor()`` above. Here is a first small addition to our toy class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = MyCompNumb(1, 2)\n",
    "z.norm()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you see, the first argument of any method is always called ``self`` and contains the object calling the method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "Create the complex number $3+4i$ and compute its norm."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "```\n",
    "w = MyCompNumb(3,4)\n",
    "w.norm()\n",
    "> 5\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "Add a method ``complex_conjugate`` to the class above, which returns the complex conjugate of the number."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "```\n",
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def complex_conjugate(self):\n",
    "        return MyCompNumb(self.Re, -self.Im)\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we try to test the new code, we encounter a problem:\n",
    "```\n",
    "w = MyCompNumb(3,4)\n",
    "w.complex_conjugate()\n",
    "> <__main__.MyCompNumb object at 0x6fd0d766f60>\n",
    "```\n",
    "In order to get a useful, readable output, we need to tell the class how an instance should be represented when trying to print it. To do this, we can define a method ``__repr__``. It is supposed to return a string which represents the value of the object. Then, when writing ``print(a)`` (or just ``a``), it secretly calls ``print(a.__repr__())``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def complex_conjugate(self):\n",
    "        return MyCompNumb(self.Re, -self.Im)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w = MyCompNumb(3,4)\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This looks reasonable on first glance, but testing a few more examples, we quickly see some issues:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.complex_conjugate()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "MyCompNumb(0,6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One of the assignments is to write a better version of the ``__repr__`` function, but for now the version above is good enough. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "Write a function ``arg`` which computes the [argument](https://en.wikipedia.org/wiki/Argument_(complex_analysis)) of the complex number, i.e. its angle with the positive real axis measured in the interval $(-\\pi, \\pi]$. If you are done early: add the optional argument ``max_arg`` so that the argument is instead specified in the interval from ``max_arg - 2 pi`` to ``max_arg``."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "Here is the basic version, without optional argument:\n",
    "```\n",
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def complex_conjugate(self):\n",
    "        return MyCompNumb(self.Re, -self.Im)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i'\n",
    "    def arg(self):\n",
    "        if self.Re == 0 and self.Im == 0:\n",
    "            raise ValueError('Argument only defined for nonzero complex numbers')\n",
    "        if self.Im >= 0:\n",
    "            result = arccos(self.Re / self.norm())\n",
    "        else:\n",
    "            result = -arccos(self.Re / self.norm())\n",
    "        return result\n",
    "```\n",
    "We see: when the number is zero, we raise an error, to alert the user that things went wrong.\n",
    "\n",
    "Here is the more fancy version with optional argument ``max_arg``:\n",
    "```\n",
    "    def arg(self, max_arg = pi):\n",
    "        if self.Re == 0 and self.Im == 0:\n",
    "            raise ValueError('Argument only defined for nonzero complex numbers')\n",
    "        if self.Im >= 0:\n",
    "            result = arccos(self.Re / self.norm())\n",
    "        else:\n",
    "            result = -arccos(self.Re / self.norm())\n",
    "        return result + 2*pi*floor((max_arg - result)/(2*pi))\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before moving on, we'll mention one more trick associated to methods of classes, called [monkey patching](https://en.wikipedia.org/wiki/Monkey_patch). The idea is that instead of declaring a method at the definition of a class, you can also attach it later, as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def is_nth_root_of_unity(self, n):\n",
    "    phi = self.arg()\n",
    "    return self.norm()==1 and simplify(phi/(2*pi)*n).is_integer()\n",
    "\n",
    "MyCompNumb.is_nth_root_of_unity = is_nth_root_of_unity"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = MyCompNumb(0,1)\n",
    "z.is_nth_root_of_unity(4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "z = MyCompNumb(1/sqrt(2),1/sqrt(2))\n",
    "z.is_nth_root_of_unity(8)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This should be done with some care, but in some cases (e.g. in exercises below) it can help to not always repeat all the code we already had before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inheritance of classes\n",
    "Sometimes we don't want to create a new class from scratch, but instead just add some feature to an existing class. In this case, we can let the new class **inherit** from the old one. This means that, by default, the methods and attributes of the old class are transferred to the new one, but one can add additional features (or overwrite methods from the old class).\n",
    "\n",
    "As an example, let's create a variant of the class ``MyCompNumb`` above, which in addition to the real and imaginary part remembers explicitly one *choice* of argument. Here is a way to do this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyCompNumbWithArg(MyCompNumb):\n",
    "    def __init__(self, RealPart, ImaginaryPart, Phi):\n",
    "        MyCompNumb.__init__(self, RealPart, ImaginaryPart)\n",
    "        self.Phi = Phi\n",
    "    def complex_conjugate(self):\n",
    "        return MyCompNumbWithArg(self.Re, -self.Im, -self.Phi)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i with arg = '+repr(self.Phi)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = MyCompNumbWithArg(1,1,pi/4); z"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What we see here:\n",
    "* The class from which we inherit (the **parent class**) is given in parentheses behind the name of the new class (the **child class**). We could also specify multiple parent classes (e.g. it is very often advisable to inherit from ``SageObject`` to get some basic methods like the option to save into a file). Apart from taking over the methods from the parents, the instances of the new class also count as instances of the old class (every complex number with argument is still an example of a complex number):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "isinstance(z, MyCompNumb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* We inherited the methods from the old function, which is why the following works:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z.norm()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* On the other hand, we have overwritten the functions ``__init__`` and ``__repr__`` to adapt to the additional argument ``Phi``. Note that by calling ``MyCompNumb.__init__`` we make sure that all the attributes set in ``MyCompNumb`` will also be available in ``MyCompNumbWithArg``."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Additionally, we have modified the function ``complex_conjugate``. Otherwise, it would return instances of ``MyCompNumb`` and not ``MyCompNumbWithArg``."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are a few things we can now do with our class:\n",
    "#### Exercise\n",
    "* Modify the ``__init__`` method of ``MyCompNumbWithArg`` to include a check that the given argument ``Phi`` actually makes sense (e.g. something like ``MyCompNumbWithArg(1,0,pi)`` should not be allowed). Raise a ``ValueError`` if it does not make sense.\n",
    "* Modify the method ``arg`` to give back the chosen argument (instead of the one in $(-\\pi, \\pi]$).\n",
    "* Write a method ``log`` which makes sense for complex numbers with an argument.<br>*Mathematical hint:* What is $\\log(z)$ for $z=r e^{i \\phi}$?<br>*Philosophical hint:* Is $\\log(z)$ naturally a complex number, or a complex number with an argument?<br>*Python hint:* Given a real number ``r`` you can compute its logarithm with ``r.log()``."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "```\n",
    "class MyCompNumbWithArg(MyCompNumb, SageObject):\n",
    "    def __init__(self, RealPart, ImaginaryPart, Phi):\n",
    "        MyCompNumb.__init__(self, RealPart, ImaginaryPart)\n",
    "        r = self.norm()\n",
    "        if not (r*cos(Phi) == RealPart and r*sin(Phi) == ImaginaryPart):\n",
    "            raise ValueError('argument does not fit with given value')\n",
    "        self.Phi = Phi\n",
    "    def arg(self):\n",
    "        return self.Phi\n",
    "    def log(self):\n",
    "        r = self.norm()\n",
    "        return MyCompNumb(r.log(), self.Phi)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i with arg = '+repr(self.Phi)\n",
    "```\n",
    "A few tests:\n",
    "```\n",
    "z = MyCompNumbWithArg(1,0,pi)\n",
    "> ... ValueError ...\n",
    "z = MyCompNumbWithArg(1,0,2*pi)\n",
    "z.arg()\n",
    "> 2*pi\n",
    "z.log()\n",
    "> 0 + 2*pi * i\n",
    "w = MyCompNumbWithArg(2,2,-7/4*pi)\n",
    "w.log()\n",
    "> log(2*sqrt(2)) + -7/4*pi * i\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arithmetic operations\n",
    "One thing we of course want to do with complex numbers is to add, subtract, multiply and divide them. This can again be done using special methods, called ``__add__``, ``__sub__``, ``__mul__``. Unfortunately, these must be present in the original declaration of the class (and *cannot* be monkey patched)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# For exercises below, add new methods here:\n",
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def complex_conjugate(self):\n",
    "        return MyCompNumb(self.Re, -self.Im)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i'\n",
    "    def arg(self):\n",
    "        if self.Re == 0 and self.Im == 0:\n",
    "            raise ValueError('Argument only defined for nonzero complex numbers')\n",
    "        if self.Im >= 0:\n",
    "            result = arccos(self.Re / self.norm())\n",
    "        else:\n",
    "            result = -arccos(self.Re / self.norm())\n",
    "        return result\n",
    "    def __add__(self, other):\n",
    "        return MyCompNumb(self.Re + other.Re, self.Im + other.Im)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "Write the functions ``__sub__``, ``__mul__`` and ``__truediv__`` for the multiplication, subtraction and division of complex numbers and test them in some examples.<br>\n",
    "If you are done early, you can also do ``__pow__`` for the \"raise to power\" function (say, for integer exponents)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "Here are the relevant functions that should be added to ``MyCompNumb``:\n",
    "```\n",
    "    def __sub__(self, other):\n",
    "        return MyCompNumb(self.Re - other.Re, self.Im - other.Im)\n",
    "    def __mul__(self, other):\n",
    "        return MyCompNumb(self.Re * other.Re - self.Im * other.Im, self.Re* other.Im + self.Im * other.Re)\n",
    "    def __truediv__(self, other):\n",
    "        if other.Re == 0 and other.Im == 0:\n",
    "            raise ValueError('division by zero!')\n",
    "        n = other.norm()^2\n",
    "        a = self * other.complex_conjugate()\n",
    "        return MyCompNumb(a.Re/n, a.Im/n)\n",
    "```\n",
    "Here are some examples:\n",
    "```\n",
    "z = MyCompNumb(1,3)\n",
    "w = MyCompNumb(-2,5)\n",
    "u = MyCompNumb(0,1)\n",
    "print(z-w)\n",
    "print(z*w)\n",
    "print(u*u)\n",
    "print(z/z)\n",
    "print(z/w)\n",
    ">\n",
    "3 + -2 * i\n",
    "-17 + -1 * i\n",
    "-1 + 0 * i\n",
    "1 + 0 * i\n",
    "13/29 + -11/29 * i\n",
    "```\n",
    "Here is the ``__pow__`` function:\n",
    "```\n",
    "    def __pow__(self, n):\n",
    "        if n<0:\n",
    "            return MyCompNumb(1,0)/(self^(-n))\n",
    "        if n==0:\n",
    "            return MyCompNumb(1,0)\n",
    "        return self*(self^(n-1))\n",
    "```\n",
    "Some examples:\n",
    "```\n",
    "u = MyCompNumb(0,1)\n",
    "[u^i for i in range(-5, 5)]\n",
    "> \n",
    "[0 + -1 * i,\n",
    " 1 + 0 * i,\n",
    " 0 + 1 * i,\n",
    " -1 + 0 * i,\n",
    " 0 + -1 * i,\n",
    " 1 + 0 * i,\n",
    " 0 + 1 * i,\n",
    " -1 + 0 * i,\n",
    " 0 + -1 * i,\n",
    " 1 + 0 * i]\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [here](https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types) for more on the Python perspective on arithmetic operations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Playing around - a class for rectangles\n",
    "Let's take a bit of time and practise all of the things above in a new example.\n",
    "#### Exercise\n",
    "Write a class ``Rectangle`` which implements rectangles in the plane $\\mathbb{R}^2$ with sides parallel to the $x$ and $y$-axis. Think about some interesting functions that you could give this class, and implement them. Here is a bit of inspiration of what this class could do:\n",
    "```\n",
    "R = Rectangle(0,2,-3,5); R\n",
    "> Rectangle [0, 2] x [-3, 5]\n",
    "R.area()\n",
    "> 16\n",
    "R + (-1,-1)\n",
    "> Rectangle [-1, 1] x [-4, 4]\n",
    "R.is_square()\n",
    "> False\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)\n",
    "<!---\n",
    "```\n",
    "class Rectangle:\n",
    "    def __init__(self, xmin, xmax, ymin, ymax):\n",
    "        self.xmin = xmin\n",
    "        self.xmax = xmax\n",
    "        self.ymin = ymin\n",
    "        self.ymax = ymax\n",
    "    def __repr__(self):\n",
    "        return 'Rectangle [{}, {}] x [{}, {}]'.format(self.xmin, self.xmax, self.ymin, self.ymax)\n",
    "    def area(self):\n",
    "        return (self.xmax-self.xmin)*(self.ymax-self.ymin)\n",
    "    def __add__(self, v):\n",
    "        return Rectangle(self.xmin+v[0], self.xmax+v[0], self.ymin+v[1], self.ymax+v[1])\n",
    "    def is_square(self):\n",
    "        return (self.xmax-self.xmin) == (self.ymax-self.ymin)\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implementing algebraic structures in SageMath\n",
    "Above we learned how to do basic arithmetic with our handmade complex numbers. However, many natural operations that we would hope to have will still not work. Here are a few examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z = MyCompNumb(2,0)\n",
    "3+z"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z == 2 # maybe should be True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z.is_zero()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In each case, the problem could be fixed in principle:\n",
    "* One could extend the methods ``__add__`` etc. to first check if ``other`` is maybe an ``Integer`` / ``Rational`` etc and have special methods for each of these (and maybe have also methods ``__radd__``, ``__rmul__`` etc).\n",
    "* Similarly, one can implement the method ``__eq__`` for checking equality.\n",
    "* One can by hand write a method ``is_zero``.\n",
    "\n",
    "However, as you can imagine, this would be a lot of work and the resulting code could easily break if the user applies it in a situation you did not foresee.\n",
    "\n",
    "A better way to do this is to use the [coercion and category framework in SageMath](https://doc.sagemath.org/html/en/thematic_tutorials/coercion_and_categories.html). \n",
    "See also the [primer on categories, parents and elements in SageMath](https://doc.sagemath.org/html/en/reference/categories/sage/categories/primer.html).\n",
    "A rough overview, explained with the example of the actual complex numbers ``CC`` in SageMath:\n",
    "\n",
    "* Instead of only having a class for complex numbers, one would have two classes: a *parent* ``ComplexField_class`` and an *element* class ``ComplexNumber``. \n",
    "* New elements are created via an *instance* of the parent class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sage.rings.complex_field import ComplexField_class\n",
    "CC = ComplexField_class(42); CC"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "z = CC(1,3); z"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These elements then remember their parents:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z.parent()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* For the parent class, you need to program some method which converts reasonable other data types (``int, float, Rational, ...``) into elements of that parent class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC(0.43)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC(int(2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC(4/5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Then, if you told your child class how to add, multiply, etc its elements (via functions ``_add_, _mul_, ...``) and it encounters something of the form ``int + ComplexNumber``, it will silently convert (**coerce**) the other class into a complex number, and then do the arithmetic operation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "z + int(6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This also works for things like the comparison that we saw above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w = CC(2)\n",
    "w == 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Even better, since many classes have a **functorial** definition in SageMath, it is in some cases possible to have arithmetic operations between elements of parents ``A,B`` such that neither can be converted into the other. The idea is to find a common parent ``C``, convert both elements into this, and then perform the arithmetic there. Take the following example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = CC(1,3); a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "R.<x,y> = PolynomialRing(QQ,2)\n",
    "b = x^2 + 3*y; b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c = a+b; c"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c.parent()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Your parent and child class should inherit from some general classes (in our case ``Field`` and ``FieldElement``). This gives them many useful methods, which you don't have to worry about at all. Look at the code of the following functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC.is_field??"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC.zero??"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, if you have implemented a function ``__eq__`` for checking equality and call ``z.is_zero()``, it will just check whether\n",
    "```\n",
    "z == z.parent().zero()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Moreover, via the **category framework** we have that SageMath knows about properties of its parent (and element) classes, and how they behave under basic operations. For instance, since ``CC`` is a field, we know that ``CC[x,y]`` is an integral domain:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CC[x,y].is_integral_domain()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To summarize: by working with parent/child classes and the coercion and category framework it is possible to save yourself a lot of work when implementing a new algebraic structure, and many constructions work almost by magic. \n",
    "\n",
    "However, this is also a relatively special problem, and explaining all the details goes beyond the scope of this lecture. Still, if you plan to implement a particular type of group/module/ring/etc as your final project, it might be worth to look into this further!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Assignments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "For the class ``MyCompNumb`` above, write a good method ``__repr__`` which also works well for negative/vanishing real and imaginary parts. Test whether this method works for all combinations of $(\\mathrm{sign}(Re), \\mathrm{sign}(Im))$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "```\n",
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def __repr__(self):\n",
    "        if self.Re == 0:\n",
    "            if self.Im == 0:\n",
    "                return('0')\n",
    "            return repr(self.Im)+' * i'\n",
    "        if self.Im == 0:\n",
    "            return repr(self.Re)\n",
    "        if self.Im < 0:\n",
    "            return repr(self.Re)+' - '+repr(-self.Im)+' * i'\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i'\n",
    "```\n",
    "Testing in a few cases:\n",
    "```\n",
    "L = [0,3,-5]\n",
    "for re, im in cartesian_product([L, L]):\n",
    "    print(MyCompNumb(re,im))\n",
    ">\n",
    "0\n",
    "3 * i\n",
    "-5 * i\n",
    "3\n",
    "3 + 3 * i\n",
    "3 - 5 * i\n",
    "-5\n",
    "-5 + 3 * i\n",
    "-5 - 5 * i\n",
    "```\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Exercise\n",
    "Write a method ``is_in_quadrant`` which takes a number ``quad`` from $1$ to $4$ and says whether the complex number is in the corresponding [quadrant](https://en.wikipedia.org/wiki/Quadrant_(plane_geometry)) of the plane of complex numbers (recall that the numbers with positive real and imaginary value are the first quadrant, and then it goes in counter-clockwise order)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Solution** (uncomment to see)<br>\n",
    "<!---\n",
    "```\n",
    "class MyCompNumb:\n",
    "    def __init__(self, RealPart, ImaginaryPart):\n",
    "        self.Re = RealPart\n",
    "        self.Im = ImaginaryPart\n",
    "    def norm(self):\n",
    "        return sqrt(self.Re^2 + self.Im^2)\n",
    "    def __repr__(self):\n",
    "        return repr(self.Re)+' + '+repr(self.Im)+' * i'\n",
    "    def is_in_quadrant(self, quad):\n",
    "        return (quad==1 and self.Re>0 and self.Im>0) or (quad==2 and self.Re<0 and self.Im>0) or \\\n",
    "        (quad==3 and self.Re<0 and self.Im<0) or (quad==4 and self.Re>0 and self.Im<0)\n",
    "```\n",
    "Of course you can also solve this using several ``if``-conditions. Note how we could have a line break within a single command using the ``\\`` symbol.\n",
    "\n",
    "Let's test it in a few cases:\n",
    "```\n",
    "z = MyCompNumb(-1,2)\n",
    "[z.is_in_quadrant(j) for j in [1,2,3,4]]\n",
    "> [False, True, False, False]\n",
    "z = MyCompNumb(-1,0)\n",
    "[z.is_in_quadrant(j) for j in [1,2,3,4]]\n",
    "> [False, False, False, False]\n",
    "```\n",
    "--->"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "SageMath 9.1",
   "language": "sage",
   "name": "sagemath"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}